{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 1. 代码规范"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 1.1 为什么要统一的编程规范\n",
    "\n",
    "- 阅读者的体验 >> 编程者的体验 >> 机器的体验。\n",
    "  + 阅读者的体验 >> 编程者的体验\n",
    "    * 研究表明，软件工程中 80% 的时间都在阅读代码。所以，为了提高开发效率，我们要优化的，不是你的打字时间，而是团队阅读的体验。\n",
    "  + 编程者的体验 >> 机器的体验\n",
    "    *  1\n",
    "  + 机器的体验也很重要\n",
    "    * google:https://github.com/google/styleguide/blob/gh-pages/pyguide.md\n",
    "- 整合进开发流程的自动化工具\n",
    "  + 靠强制代码评审和强制静态或者动态 linter\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": []
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## PEP8\n",
    "---\n",
    "\n",
    "- PEP: Python Enhancement Proposal python增强规范；"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "- 缩进规范：\n",
    "  + 请选择四个空格的缩进，不要使用 Tab，更不要 Tab 和空格混着用\n",
    "  + 每行最大长度请限制在 79 个字符。\n",
    "- 空行规范：\n",
    "  + 全局的类和函数的上方需要空两个空行，\n",
    "  + 而类的函数之间需要空一个空行\n",
    "  + 全局的类和函数的上方需要空两个空行，而类的函数之间需要空一个空行\n",
    "  + 全局的类和函数的上方需要空两个空行，而类的函数之间需要空一个空行\n",
    "\n",
    "- 空格规范：\n",
    "  +  函数的参数列表中，调用函数的参数列表中会出现逗号，请注意逗号后要跟一个空格，这是英语的使用习惯，也能让每个参数独立阅读，更清晰\n",
    "  + 冒号经常被用来初始化字典，冒号后面也要跟一个空格\n",
    "  + 在#后、注释前加一个空格。 \n",
    "- 换行规范：\n",
    "  + 通过括号来将过长的运算进行封装，此时虽然跨行，但是仍处于一个逻辑引用之下\n",
    "  + 则是通过换行符来实现。这个方法更为直接\n",
    "- 文档规范：\n",
    "  + 所有 import 尽量放在开头，这个没什么说的，毕竟到处 import 会让人很难看清楚文件之间的依赖关系，运行时 import 也可能会导致潜在的效率问题和其他风险。\n",
    "  + 不要使用 import 一次导入多个模块。虽然我们可以在一行中 import 多个模块，并用逗号分隔，但请不要这么做。import time, os 是 PEP 8 不推荐的做法\n",
    "  + from module import func 这样的语句，请确保 func 在本文件中不会出现命名冲突。不过，你其实可以通过 from module import func as new_func 来进行重命名，从而避免冲突。\n",
    "- 注释规范:\n",
    "  + 一份优秀的代码，离不开优秀的注释。\n",
    "  + 行注释并不是很推荐的方式。\n",
    "\n",
    "- 文档描述:\n",
    "  + 用三个双引号开始、三个双引号结尾。我们首先用一句话简单说明这个函数做什么，然后跟一段话来详细解释；再往后是参数列表、参数格式、返回值格式。\n",
    "\n",
    "- 命名规范:\n",
    "  + 变量使用小写，通过下划线串联起来，\n",
    "  + 对于常量，最好的做法是全部大写，并通过下划线连接，例如：WAIT_TIME、\n",
    "  + 不要过于吝啬一个变量名的长度。当然，在合理描述这个变量背后代表的对象后，一定的精简能力也是必要的。\n",
    "- 代码分解技巧：\n",
    "  + 编程中一个核心思想是，不写重复代码。重复代码大概率可以通过使用条件、循环、构造函数和类来解决。而另一个核心思想则是，减少迭代层数，尽可能让 Python 代码扁平化，毕竟，人的大脑无法处理过多的栈操作。\n",
    "  + 代码层层缩进 -> 代码扁平化\n",
    "  + 一个函数的粒度应该尽可能细，不要让一个函数做太多的事情\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "缩进规范：\n",
    "1. 使用四空格缩进\n",
    "2. 每行最大长度79个字符\n",
    "\n",
    "空行规范：\n",
    "1. 全局的(文件级别的)类和全局的函数上方要有两个空行\n",
    "2. 类中的函数上方要有一个空行\n",
    "3. 函数内部不同意群的代码块之前要有一个空行\n",
    "4. 不要把多行语句合并为一行(即不要使用分号分隔多条语句)\n",
    "5. 当使用控制语句if/while/for时，即使执行语句只有一行命令，也需要另起一行\n",
    "6. 代码文件尾部有且只有一个空行\n",
    "\n",
    "空格规范：\n",
    "1. 函数的参数之间要有一个空格\n",
    "2. 列表、元组、字典的元素之间要有一个空格\n",
    "3. 字典的冒号之后要有一个空格\n",
    "4. 使用#注释的话，#后要有一个空格\n",
    "5. 操作符(例如+，-，*，/，&，|，=，==，!=)两边都要有一个空格，不过括号(包括小括号、中括号和大括号)内的两端不需要空格\n",
    "\n",
    "换行规范：\n",
    "1. 一般我们通过代码逻辑拆分等手段来控制每行的最大长度不超过79个字符，但有些时候单行代码还是不可避免的会超过这个限制，这个时候就需要通过换行来解决问题了。\n",
    "2. 两种实现换行的方法：\n",
    "第一种，通过小括号进行封装，此时虽然跨行，但是仍处于一个逻辑引用之下。比如函数参数列表的场景、过长的运算语句场景\n",
    "第二种，直接通过换行符(\\)实现\n",
    "\n",
    "文档规范：\n",
    "1. 所有import尽量放在代码文件的头部位置\n",
    "2. 每行import只导入一个对象\n",
    "3. 当我们使用from xxx import xxx时，import后面跟着的对象要是一个package(包对应代码目录)或者module(模块对应代码文件)，不要是一个类或者一个函数\n",
    "\n",
    "注释规范：\n",
    "1. 代码块注释，在代码块上一行的相同缩进处以 # 开始书写注释\n",
    "2. 代码行注释，在代码行的尾部跟2个空格，然后以 # 开始书写注释，行注释尽量少写\n",
    "3. 英文注释开头要大写，结尾要写标点符号，避免语法错误和逻辑错误，中文注释也是相同要求\n",
    "4. 改动代码逻辑时，一定要及时更新相关的注释\n",
    "\n",
    "文档描述规范：\n",
    " 三个双引号开始、三个双引号结尾；\n",
    " 首先用一句话简单说明这个函数做什么，然后跟一段话来详细解释；\n",
    "再往后是参数列表、参数格式、返回值格式的描述。\n",
    "\n",
    "命名规范：\n",
    "1. 变量名，要全部小写，多个词通过下划线连接，可以使用单字符变量名的场景，比如for i in range(n)这种变量没有实际意义的情况\n",
    "2. 类的私有变量名，变量名前需要加2个下划线\n",
    "3. 常量名，要全部大写，多个词通过下划线连接\n",
    "4. 函数名，要全部小写，多个词通过下划线连接\n",
    "5. 类名，要求驼峰形式，即单词首字母大写，多个词的话，每个词首字母大写然后直接拼接\n",
    "6. 命名需要做到名如其意，不要吝啬名字的长度\n",
    "\n",
    "代码分解技巧：\n",
    "1. 不写重复代码，重复代码可以通过使用条件、循环、函数和类来解决\n",
    "2. 减少迭代层数，让代码扁平化\n",
    "3. 函数拆分，函数的粒度尽可能细，也就是一个函数不要做太多事情\n",
    "4. 类的拆分，如果一个类中有多个属性描述的是同一类事物，就可以把这些属性拆分出来新建一个单独的类\n",
    "5. 模块化，若项目偏大，要为不同功能模块创建独立的目录或文件，通过import互相关联"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.12.9"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}
